<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Cluster Health | Elasticsearch: The Definitive Guide [2.x] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch: The Definitive Guide [2.x]">
<link rel="up" href="cluster-admin.html" title="Monitoring">
<link rel="prev" href="marvel.html" title="Marvel for Monitoring">
<link rel="next" href="_monitoring_individual_nodes.html" title="Monitoring Individual Nodes">
<meta name="DC.type" content="Learn/Docs/Legacy/Elasticsearch/Definitive Guide/2.x">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="2.x">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<p>
  <strong>WARNING</strong>: The 2.x versions of Elasticsearch have passed their
  <a href="https://www.elastic.co/support/eol">EOL dates</a>. If you are running
  a 2.x version, we strongly advise you to upgrade.
</p>
<p>
  This documentation is no longer maintained and may be removed. For the latest
  information, see the <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html">current
  Elasticsearch documentation</a>.
</p>
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch: The Definitive Guide [2.x]</a></span>
»
<span class="breadcrumb-link"><a href="administration.html">Administration, Monitoring, and Deployment</a></span>
»
<span class="breadcrumb-link"><a href="cluster-admin.html">Monitoring</a></span>
»
<span class="breadcrumb-node">Cluster Health</span>
</div>
<div class="navheader">
<span class="prev">
<a href="marvel.html">« Marvel for Monitoring</a>
</span>
<span class="next">
<a href="_monitoring_individual_nodes.html">Monitoring Individual Nodes »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="_cluster_health"></a>Cluster Health<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch-definitive-guide/edit/2.x/500_Cluster_Admin/20_health.asciidoc">edit</a>
</h2>
</div></div></div>
<p>An Elasticsearch cluster may consist of a single node with a single index.  Or it
may have a hundred data nodes, three dedicated masters, a few dozen client nodes—​all operating on a thousand indices (and tens of thousands of shards).</p>
<p>No matter the scale of the cluster, you’ll want a quick way to assess the status
of your cluster.  The <code class="literal">Cluster Health</code> API fills that role.  You can think of it
as a 10,000-foot view of your cluster.  It can reassure you that everything
is all right, or alert you to a problem somewhere in your cluster.</p>
<p>Let’s execute a <code class="literal">cluster-health</code> API and see what the response looks like:</p>
<div class="pre_wrapper lang-bash">
<pre class="programlisting prettyprint lang-bash">GET _cluster/health</pre>
</div>
<p>Like other APIs in Elasticsearch, <code class="literal">cluster-health</code> will return a JSON response.
This makes it convenient to parse for automation and alerting.  The response
contains some critical information about your cluster:</p>
<div class="pre_wrapper lang-js">
<pre class="programlisting prettyprint lang-js">{
   "cluster_name": "elasticsearch_zach",
   "status": "green",
   "timed_out": false,
   "number_of_nodes": 1,
   "number_of_data_nodes": 1,
   "active_primary_shards": 10,
   "active_shards": 10,
   "relocating_shards": 0,
   "initializing_shards": 0,
   "unassigned_shards": 0
}</pre>
</div>
<p>The most important piece of information in the response is the <code class="literal">status</code> field.
The status may be one of three values:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">green</code>
</span>
</dt>
<dd>
    All primary and replica shards are allocated. Your cluster is 100%
operational.
</dd>
<dt>
<span class="term">
<code class="literal">yellow</code>
</span>
</dt>
<dd>
    All primary shards are allocated, but at least one replica is missing.
No data is missing, so search results will still be complete. However,  your
high availability is compromised to some degree.  If <em>more</em> shards disappear, you
might lose data.  Think of <code class="literal">yellow</code> as a warning that should prompt investigation.
</dd>
<dt>
<span class="term">
<code class="literal">red</code>
</span>
</dt>
<dd>
    At least one primary shard (and all of its replicas) is missing. This means
that you are missing data: searches will return partial results, and indexing
into that shard will return an exception.
</dd>
</dl>
</div>
<p>The <code class="literal">green</code>/<code class="literal">yellow</code>/<code class="literal">red</code> status is a great way to glance at your cluster and understand
what’s going on.  The rest of the metrics give you a general summary of your cluster:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">number_of_nodes</code> and <code class="literal">number_of_data_nodes</code> are fairly self-descriptive.
</li>
<li class="listitem">
<code class="literal">active_primary_shards</code> indicates the number of primary shards in your cluster. This
is an aggregate total across all indices.
</li>
<li class="listitem">
<code class="literal">active_shards</code> is an aggregate total of <em>all</em> shards across all indices, which
includes replica shards.
</li>
<li class="listitem">
<code class="literal">relocating_shards</code> shows the number of shards that are currently moving from
one node to another node.  This number is often zero, but can increase when
Elasticsearch decides a cluster is not properly balanced, a new node is added,
or a node is taken down, for example.
</li>
<li class="listitem">
<code class="literal">initializing_shards</code> is a count of shards that are being freshly created. For
example, when you first create an index, the shards will all briefly reside in
<code class="literal">initializing</code> state.  This is typically a transient event, and shards shouldn’t
linger in <code class="literal">initializing</code> too long.  You may also see initializing shards when a
node is first restarted: as shards are loaded from disk, they start as <code class="literal">initializing</code>.
</li>
<li class="listitem">
<code class="literal">unassigned_shards</code> are shards that exist in the cluster state, but cannot be
found in the cluster itself.  A common source of unassigned shards are unassigned
replicas.  For example, an index with five shards and one replica will have five unassigned
replicas in a single-node cluster.  Unassigned shards will also be present if your
cluster is <code class="literal">red</code> (since primaries are missing).
</li>
</ul>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_drilling_deeper_finding_problematic_indices"></a>Drilling Deeper: Finding Problematic Indices<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch-definitive-guide/edit/2.x/500_Cluster_Admin/20_health.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Imagine something goes wrong one day, and you notice that your cluster health
looks like this:</p>
<div class="pre_wrapper lang-js">
<pre class="programlisting prettyprint lang-js">{
   "cluster_name": "elasticsearch_zach",
   "status": "red",
   "timed_out": false,
   "number_of_nodes": 8,
   "number_of_data_nodes": 8,
   "active_primary_shards": 90,
   "active_shards": 180,
   "relocating_shards": 0,
   "initializing_shards": 0,
   "unassigned_shards": 20
}</pre>
</div>
<p>OK, so what can we deduce from this health status?  Well, our cluster is <code class="literal">red</code>,
which means we are missing data (primary + replicas).  We know our cluster has
10 nodes, but see only 8 data nodes listed in the health.  Two of our nodes
have gone missing.  We see that there are 20 unassigned shards.</p>
<p>That’s about all the information we can glean.  The nature of those missing
shards are still a mystery.  Are we missing 20 indices with 1 primary shard each?
Or 1 index with 20 primary shards? Or 10 indices with 1 primary + 1 replica?
Which index?</p>
<p>To answer these questions, we need to ask <code class="literal">cluster-health</code> for a little more
information by using the <code class="literal">level</code> parameter:</p>
<div class="pre_wrapper lang-bash">
<pre class="programlisting prettyprint lang-bash">GET _cluster/health?level=indices</pre>
</div>
<p>This parameter will make the <code class="literal">cluster-health</code> API add a list of indices in our
cluster and details about each of those indices (status, number of shards,
unassigned shards, and so forth):</p>
<div class="pre_wrapper lang-js">
<pre class="programlisting prettyprint lang-js">{
   "cluster_name": "elasticsearch_zach",
   "status": "red",
   "timed_out": false,
   "number_of_nodes": 8,
   "number_of_data_nodes": 8,
   "active_primary_shards": 90,
   "active_shards": 180,
   "relocating_shards": 0,
   "initializing_shards": 0,
   "unassigned_shards": 20
   "indices": {
      "v1": {
         "status": "green",
         "number_of_shards": 10,
         "number_of_replicas": 1,
         "active_primary_shards": 10,
         "active_shards": 20,
         "relocating_shards": 0,
         "initializing_shards": 0,
         "unassigned_shards": 0
      },
      "v2": {
         "status": "red", <a id="CO299-1"></a><i class="conum" data-value="1"></i>
         "number_of_shards": 10,
         "number_of_replicas": 1,
         "active_primary_shards": 0,
         "active_shards": 0,
         "relocating_shards": 0,
         "initializing_shards": 0,
         "unassigned_shards": 20 <a id="CO299-2"></a><i class="conum" data-value="2"></i>
      },
      "v3": {
         "status": "green",
         "number_of_shards": 10,
         "number_of_replicas": 1,
         "active_primary_shards": 10,
         "active_shards": 20,
         "relocating_shards": 0,
         "initializing_shards": 0,
         "unassigned_shards": 0
      },
      ....
   }
}</pre>
</div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO299-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>We can now see that the <code class="literal">v2</code> index is the index that has made the cluster <code class="literal">red</code>.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO299-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>And it becomes clear that all 20 missing shards are from this index.</p>
</td>
</tr>
</table>
</div>
<p>Once we ask for the indices output, it becomes immediately clear which index is
having problems: the <code class="literal">v2</code> index.  We also see that the index has 10 primary shards
and one replica, and that all 20 shards are missing.  Presumably these 20 shards
were on the two nodes that are missing from our cluster.</p>
<p>The <code class="literal">level</code> parameter accepts one more option:</p>
<div class="pre_wrapper lang-bash">
<pre class="programlisting prettyprint lang-bash">GET _cluster/health?level=shards</pre>
</div>
<p>The <code class="literal">shards</code> option will provide a very verbose output, which lists the status
and location of every shard inside every index.  This output is sometimes useful,
but because of the verbosity can be difficult to work with.  Once you know the index
that is having problems, other APIs that we discuss in this chapter will tend
to be more helpful.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_blocking_for_status_changes"></a>Blocking for Status Changes<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch-definitive-guide/edit/2.x/500_Cluster_Admin/20_health.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The <code class="literal">cluster-health</code> API has another neat trick that is useful when building
unit and integration tests, or automated scripts that work with Elasticsearch.
You can specify a <code class="literal">wait_for_status</code> parameter, which will only return after the status is satisfied.  For example:</p>
<div class="pre_wrapper lang-bash">
<pre class="programlisting prettyprint lang-bash">GET _cluster/health?wait_for_status=green</pre>
</div>
<p>This call will <em>block</em> (not return control to your program) until the <code class="literal">cluster-health</code> has turned <code class="literal">green</code>, meaning all primary and replica shards have been allocated.
This is important for automated scripts and tests.</p>
<p>If you create an index, Elasticsearch must broadcast the change in cluster state
to all nodes.  Those nodes must initialize those new shards, and then respond to the
master that the shards are <code class="literal">Started</code>.  This process is fast, but because of network
latency may take 10–20ms.</p>
<p>If you have an automated script that (a) creates an index and then (b) immediately
attempts to index a document, this operation may fail, because the index has not
been fully initialized yet.  The time between (a) and (b) will likely be less than 1ms—​not nearly enough time to account for network latency.</p>
<p>Rather than sleeping, just have your script/test call <code class="literal">cluster-health</code> with
a <code class="literal">wait_for_status</code> parameter.  As soon as the index is fully created, the <code class="literal">cluster-health</code> will change to <code class="literal">green</code>, the call will return control to your script, and you may
begin indexing.</p>
<p>Valid options are <code class="literal">green</code>, <code class="literal">yellow</code>, and <code class="literal">red</code>.  The call will return when the
requested status (or one "higher") is reached. For example, if you request <code class="literal">yellow</code>,
a status change to <code class="literal">yellow</code> or <code class="literal">green</code> will unblock the call.</p>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="marvel.html">« Marvel for Monitoring</a>
</span>
<span class="next">
<a href="_monitoring_individual_nodes.html">Monitoring Individual Nodes »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
